Skip to content

issue-tracker: GitHub issues drive app as the host for the Devonian bridge - #113

Merged
michielbdejong merged 3 commits into
mainfrom
claude/issue-100-github-bridge-host
Sep 24, 2026
Merged

michielbdejong merged 3 commits into
mainfrom
claude/issue-100-github-bridge-host

Conversation

@michielbdejong

Copy link
Copy Markdown
Contributor

Refs #100

Summary

The Devonian GitHub issues bridge gets a host again: an iframe drive app in integrations/issue-tracker/app/, the same shape as pets/app/ and notion/app/. One app install syncs one repository.

  • Flow. The app shows "Connect GitHub", which opens the host's consent bar through store.proxy.connect with platform github-issues. You then type the repository as owner/name. The app creates its own columns and imports issues and comments into its table. Sync runs when the view opens and when you click "Sync now".
  • Bridge wiring.
    • The bridge runs unchanged. proxyTransport's existing dispatch hook calls store.proxy.request, so the frame never holds a connection code.
    • AtomicPort runs over a new adapter, app/frameStore.ts.
    • The snapshot and write journal are stored as JSON text on a sync resource inside the app's own subtree.
  • Review before provider writes. This is new in devonian/github-issues/review.mjs.
    • Every GitHub create and update is held until someone clicks "Send N changes to GitHub".
    • An approval covers that exact content only. If the change is edited after review, it is held again.
    • Imports into the table are not held, the same as in pets and notion.
  • Recovery.
    • A same-field conflict pauses sync and offers "Keep GitHub's version" or "Keep this table's version". This uses the new Bridge.resolveConflict, which moves only the conflicting fields' baseline.
    • A 401 or a connection the host no longer holds offers "Reconnect GitHub".
    • If a write's response is lost, the next pass reads the issue back from GitHub first. An update that did not land is offered for review again, marked "unconfirmed". A create is never resent: the journal reports "Uncertain GitHub write" and sync stays paused.
  • Mock fixture. The mock proxy's GitHub fixture now seeds atomic-fixture/tracker with two issues and one comment. The e2e needs this because the mock proxy runs in a separate process, so the test can't seed it directly.

Host findings (atomic-server bae5cdbe3)

  • A resolved save or newResource from the frame is an acknowledged /app-write commit (hostStore.ts writeAsApp).
  • Frame reads come from the host page's cache. In the e2e, a row the page had already loaded still showed its old value 5 s after the app saved it. frameStore.ts corrects its own reads for the app's own saves rather than waiting for the cache. This may be worth an atomic-server issue.
  • The host's query checks the page's local (OPFS) index first and can miss a resource the app has just created. frameStore.ts remembers every subject it has seen or created in the sync state and adds those back to query results.

Verified

  • node integrations/tooling/run-lane.mjs issue-tracker: the unit tier passes (79 tests), and the new e2e tier passed twice locally against the shared bae5cdbe3 build.
  • app/sync.test.ts uses an in-memory host and the same fixture. It covers:
    • a host whose reads never show the app's own saves
    • lost responses for updates and for creates, both when the write landed and when it didn't
    • host refusals that happen before anything is sent
    • reconnect
  • app/build.test.ts checks that the bundle (about 86 KB) is one ES module with no storage or fetch calls of its own and no Automerge, and it typechecks app/.
  • localthought lane (typecheck and unit, it also uses the GitHub fixture), node --test integrations/tooling/, tsc -p integrations/tsconfig.e2e.json, and oxfmt --check integrations all pass.

Not verified / not done

Decisions for the maintainer

  1. Where the sync state lives. It is in the app's own subtree for now. Because of that, it syncs across devices, and /app-write has no compare-and-swap, so two tabs or devices syncing the same app at once are not protected against each other. The design (issue-tracker: frontend design, mockups and implementation issue drafts (#89) #103) proposed a per-browser storage op in the host instead, which would need atomic-server work.
  2. Is the app-level review gate the boundary you want before Design a replacement host for actions/approval plumbing now that the Rust sandbox is gone for GitHub #11? Imports into the table are not gated.
  3. Package location. devonian@0.7.0 is pinned in app/package.json, not in the plugin folder, because certify.mjs would treat a plugin-level package.json as a sandbox package. This required a one-line change to both install loops in ci.yml.
  4. syncables@0.18.0 is not used. The bridge's GitHub port already handles pagination.

Changes outside integrations/issue-tracker/

  • integrations/lanes.json: the issue-tracker lane gains the e2e tier and the spec.
  • .github/workflows/ci.yml: both "Install plugin npm dependencies" loops now also install integrations/*/app/pnpm-lock.yaml.

Overlaps

🤖 Generated with Claude Code

🤖 Generated with Claude Code

Michiel de Jong and others added 3 commits September 24, 2026 13:33
…relay errors

Bridge: a port may throw ReviewRequired before any request; the pass
records the write in bridge.held and carries on. A held write never sent
anything, so the next pass plans it again from both sides. reviewGate()
wraps the GitHub port and lets through only the exact (entity, id, value)
a person approved. resolveConflict(subject, keep) moves only the
conflicting fields' baseline to the other side. Conflict errors carry
subject, entity and fields.

proxyTransport's dispatch path keeps the host's error text, and drops the
journal entry only when the dispatcher marks the error notSent.

Refs #100

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
An iframe drive app (app/, the pets/notion shape) that runs the Devonian
GitHub issues Bridge for one repository per install: connect through the
host's consent bar, type owner/name, import issues and comments into the
app's own table, and sync on open and on "Sync now".

- Transport: proxyTransport's dispatch over store.proxy.request; the frame
  never holds a connection code, the write journal still guards uncertain
  writes, and host refusals before sending are not uncertain.
- Atomic side: AtomicPort unchanged, over frameStore.ts, which gives the
  frame's PluginStore the predicates target.mjs reads, corrects reads for
  the app's own saves (the host page's cache did not show them within 5 s
  in the e2e) and remembers subjects the OPFS-first query can miss.
- State: Bridge snapshot and journal as JSON text on a sync resource in
  the app's subtree (no IndexedDB in a null-origin frame).
- Review: every GitHub create/update is held until "Send N changes to
  GitHub" approves that exact content. Conflicts pause with "Keep
  GitHub's version" / "Keep this table's version". 401 and lost
  connections offer "Reconnect GitHub".
- npm devonian@0.7.0 in app/package.json (not the plugin root, which
  certify.mjs would treat as a sandbox package); ci.yml installs
  integrations/*/app/pnpm-lock.yaml too.
- The mock proxy's github-issues fixture seeds atomic-fixture/tracker.
- e2e (new lane tier): connect, import, reload + unchanged refresh, a
  reviewed close of #1, and a title conflict settled for GitHub's side.

No catalog entry: there is no catalog install flow for drive apps (#94).

Refs #100

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Refs #100

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant